neuron Carrier Experience API

⚠️ Error Handling Guide — Neuron Carrier Experience API

This page explains the different error types you may encounter when interacting with the Neuron Carrier Experience API.

Each error includes an HTTP status code, an optional custom Neuron error code, and a descriptive message to help diagnose issues quickly.

🧩 Error Codes Overview

🛠️ Error Response Structure

Most errors follow a standard Neuron error format (except some 401 responses):

{
  "code": "carrier_id_mismatch",
  "message": "Carrier Id mismatch. Seek admin support",
  "timestamp": "2023-07-05T12:25:15.283Z",
  "correlationId": "d714a266-b58a-4af3-b42c-4ca2bc90ce8b",
  "source": {
    "name": "carrier-experience-api-v1",
    "layer": "API_EXPERIENCE"
  }
}

🔍 Detailed Error Explanations

❗ 400 — Bad Request

Returned when the request is malformed or missing required data.

{
  "code": "bad_request",
  "message": "Bad Request. Multiple error types detected, see causes for more details",
  "timestamp": "2023-07-05T12:23:41.046Z",
  "correlationId": "f6336636-cfad-49b8-87b7-b9954f04c925",
  "source": {
    "name": "carrier-experience-api-v1",
    "layer": "API_EXPERIENCE"
  },
  "causes": [
    {
      "code": "data_validation",
      "message": "/exposure required key not found"
    }
  ]
}

🔐 401 — Unauthorized

Returned when authentication fails.

{ "error": "Invalid Client Id" }
{ "error": "Invalid Token" }
{ "error": "Authentication denied." }

⚠️ 401 responses do not use the standard error structure.

🚫 403 — Forbidden

Returned when authentication succeeds but the caller does not have access rights.

{
  "code": "carrier_id_mismatch",
  "message": "Carrier Id mismatch. Seek admin support",
  "timestamp": "2023-07-05T12:25:15.283Z",
  "correlationId": "d714a266-b58a-4af3-b42c-4ca2bc90ce8b",
  "source": {
    "name": "carrier-experience-api-v1",
    "layer": "API_EXPERIENCE"
  }
}

🔎 404 — Not Found

Returned when a referenced carrier-related resource cannot be located.

{
  "code": "carrier_not_found",
  "message": "No carrier found with details provided.",
  "timestamp": "2023-07-05T12:24:31.987Z",
  "correlationId": "57aa32cc-9361-45a4-b19e-5436831bf22a",
  "source": {
    "name": "carrier-experience-api-v1",
    "layer": "API_EXPERIENCE"
  }
}

🚧 405 — Method Not Allowed

Returned when the HTTP method is not supported.

⏱️ 429 — Too Many Requests

Returned when rate limits are exceeded.

{ "error": "Quota has been exceeded" }

💥 500 — Internal Server Error

General server-side failure.

🔄 502 — Bad Gateway

Returned when an upstream dependency fails.

🛑 503 — Service Unavailable

Used during system downtime, outages, or temporary unavailability.

⏳ 504 — Gateway Timeout

Returned when a downstream service takes too long to respond.

🧭 Custom Neuron Error Codes

Updated to replace all “risk” references with “carrier.”

Example

{
  "code": "carrier_id_mismatch",
  "message": "Carrier Id mismatch. Seek admin support",
  "timestamp": "2023-07-05T12:25:15.283Z",
  "correlationId": "d714a266-b58a-4af3-b42c-4ca2bc90ce8b",
  "source": {
    "name": "carrier-experience-api-v1",
    "layer": "API_EXPERIENCE"
  }
}

🆘 Troubleshooting

If you encounter an error not listed here or need further help:

📩 Contact support.neuron@wtwco.com

Include your correlationId for faster diagnostics.